package uk.org.fuzelogik.eldaw.auth;

/**
 * An authentication strategy that delegates the actual authentication process
 * to a third party, accessible over HTTP(S). A good example of this sort of
 * authentication mechanism is <a href="http://openid.net/">OpenID</a>.
 * 
 * @author cgdavies
 */
public interface IDelegatedAuthenticationStrategy extends
	IAuthenticationStrategy
{
	/**
	 * Begins the authentication process for this strategy.
	 * 
	 * @param userId the ID of the user to authenticate
	 * @return the URL that the user needs to be redirected to in order to
	 * authenticate themselves
	 * @throws DelegatedAuthenticationException if any problem occurred trying
	 * to initiate the delegated authentication process
	 */
	public String beginAuthentication( String userId )
		throws DelegatedAuthenticationException;

	/**
	 * @return <code>true</code> if the user has been redirected to the
	 * authentication page, but the gateway hasn't reported on the success of
	 * the authentication attempt yet
	 */
	public boolean isAuthenticationInProcess();

	/**
	 * Invoked when the third-party authentication service notifies the system
	 * of a successful or unsuccessful login.
	 * 
	 * @param userId the ID that the user successfully authenticated as, or
	 * <code>null</code> if authentication failed
	 */
	public void setAuthenticatedIdentity( String userId );
}
